feat(cosim): rolling per-cycle hash checkpoints, the rung-0 compare surface - #433

…urface

The Fabric plan puts this in rung 0 rather than bolting it on later, and the
reason is that the constraint nobody budgets for in co-simulation is trace
VOLUME, not simulation time. That is now measured rather than projected: three
frames of AccuracyCoin is 89,343 CPU cycles, which is 5,372,427 bytes of
irq.csv against 352 bytes of ckpt.bin. A factor of 15,263, on a real export.

So both sides chain a hash over the per-cycle tuple and compare checkpoints
every 4096 cycles; the first mismatch names a 4096-cycle window and only that
window is re-run with full capture.

WHAT IS HASHED IS A DECISION ABOUT HARDWARE, NOT ABOUT CONVENIENCE

CycleRecord carries 29 fields and most of them are RustyNES's MODEL --
dmc_abort_delay_post, apu_phase_post, dma_cycles_owed. Gating on those would
force an independent implementation to transliterate a Rust data structure,
which is bad hardware, and on a programme built on never reading a reference
implementation it is an odd form of self-derivation.

checkpoint::Observable is the subset a device-under-test can genuinely produce,
and Observable::from_cycle_record is the single place the partition is applied,
so widening it has to pass a test that perturbs EVERY dropped field at once and
asserts the hash does not move. Its converse is there too, because otherwise
that test passes just as well if the projection drops everything.

Two members needed their caveats stated rather than buried.

  THE IRQ LINE IS ONE WIRE. CycleRecord attributes each sample to the mapper or
  the APU; hardware has a single wire-OR'd /IRQ pin and cannot make that
  distinction, so the pairs are OR'd before hashing. Hashing them apart would
  fail a correct DUT for disagreeing about something it has no way to observe.

  pc IS DUT-OBSERVABLE, NOT PIN-OBSERVABLE. The 6502 does not expose its
  program counter. It is in because the testbench wrapper can expose the
  register and rung 1 compares it directly, but a pc-only mismatch means
  something weaker than a bus mismatch.

a12_events is excluded for SCOPE, not observability -- A12 transitions really
are visible on the cartridge connector -- and becomes a gate when the PPU rung
opens rather than being dropped.

THE HASH IS FNV-1a 64 FOR EXACTLY ONE REASON

A C++ testbench must be able to reimplement it without a library. The top risk
at this rung is a format-packing mismatch masquerading as an RTL bug, so
encode() fixes a 16-byte little-endian layout with an explicit zero pad byte --
the C++ side cannot hash uninitialised struct padding, which is the classic way
two correct implementations of the same layout disagree -- and both the layout
and the resulting hash are pinned to a hardcoded vector. A reordered field
fails that test rather than producing a phantom RTL defect on the next run.

THREE ANSWERS, AND THE THIRD IS THE POINT

checkpoint_diff exits 0 identical, 1 diverged with the window printed, 2
usage/IO, and 3 INCONCLUSIVE. A truncated run, a DUT that stopped early, and
two runs at different intervals all produce "no divergence was found", and
reporting that as agreement is this project's recurring failure. Cycle
ALIGNMENT is checked before the hash, because two streams checkpointing at
different cycles cover different spans, so calling their difference a
divergence would send a full-capture re-run at a window where nothing is wrong.

All three are demonstrated on real exported output, not only in unit tests:

  identical  -> "checkpoints match: 22 compared, 0 divergences"          exit 0
  one bit    -> "DIVERGED at checkpoint 7 ... cycles (28679, 32775]"     exit 1
  truncated  -> "INCONCLUSIVE (this is not a pass): ... one side stopped early"
                                                                        exit 3

TWO HAZARDS FOUND WHILE BUILDING IT

IrqTrace::push SILENTLY DROPS records once it reaches the capacity it was armed
with, behind an overflow counter nobody has to read. A hash over an overflowed
trace covers fewer cycles than it claims, and the two sides then disagree for a
reason that has nothing to do with the DUT -- which is worse than useless,
because it looks like a legitimate divergence. take_checkpoints now refuses
with CheckpointError::TraceOverflowed naming the capacity to retry with,
rn_write_checkpoints returns -5, and the exporter aborts rather than writing a
short stream.

Bus::take_irq_trace MOVES the trace out, so asking for the CSV and then the
checkpoints returns None for whichever came second -- and None there is
indistinguishable from "never armed", which the exporter would have reported as
a missing-output warning rather than as the ordering bug it is.
Oracle::take_irq_artifacts derives both from one take, and the hazard is pinned
by a test so it stays a documented behaviour.

Also fixed, and it is not cosmetic:

THE EXCLUDED CRATE'S LOCKFILE WAS SILENTLY GITIGNORED. .gitignore carries a
bare `Cargo.lock`, which matches at any depth, paired with a `!/Cargo.lock`
re-include naming only the workspace root -- written when there was exactly one
lockfile. Excluding rustynes-cosim from the workspace in v2.4.1 gave it its own
resolve and its own lockfile, which the bare rule then ignored, so CI
re-resolved its dependency graph on every run. It matters more here than for an
ordinary crate: this crate emits the goldens an external NES implementation is
verified against, and its manifest records the emulator version rather than the
resolve, so a dependency moving underneath it would be invisible in exactly the
artifact whose job is to establish provenance. cosim_manifest_audit.rs now
asserts the lockfile is TRACKED rather than merely present, demonstrated to
fail by un-tracking it and re-running.

Gates. The emulation core is untouched -- no file under
crates/rustynes-{cpu,ppu,apu,mappers,core} changes -- so AccuracyCoin 141/141
and nestest 0-diff hold by construction rather than by re-measurement.

  fmt (workspace AND the excluded crate, which --all does not reach)
  clippy --workspace --all-targets, clippy on the excluded crate,
  both wasm32 invocations, the no_std thumbv7em build,
  rustdoc -D warnings for the workspace AND the excluded crate,
  markdownlint on both changed documents.

  126 workspace suites / 2223 passed / 0 failed
    4 excluded-crate suites /   35 passed / 0 failed

One rustdoc note worth recording: an intra-doc link to a `#[cfg(test)]` item is
a BROKEN link under -D warnings, because test items are not in the documented
tree. Three such links were written and all three are now plain code spans.
Same shape as the existing rule about linking to a feature-gated dependency.